
/*
 * Copyright (C) Igor Sysoev
 * Copyright (C) Nginx, Inc.
 */


#ifndef _NGX_CONNECTION_H_INCLUDED_
#define _NGX_CONNECTION_H_INCLUDED_


#include <ngx_config.h>
#include <ngx_core.h>


typedef struct ngx_listening_s  ngx_listening_t;

struct ngx_listening_s {
    ngx_socket_t        fd;

    struct sockaddr    *sockaddr;
    socklen_t           socklen;    /* size of sockaddr */
    size_t              addr_text_max_len;
    ngx_str_t           addr_text;

    int                 type;

    int                 backlog; //fzc: 监听队列长度 for listen()
    int                 rcvbuf;
    int                 sndbuf;
#if (NGX_HAVE_KEEPALIVE_TUNABLE)
    int                 keepidle;
    int                 keepintvl;
    int                 keepcnt;
#endif

    /* handler of accepted connection */
    ngx_connection_handler_pt   handler; //fzc: http框架在ngx_event_accept中会将handler赋值为ngx_http_init_connection

    void               *servers;  /* array of ngx_http_in_addr_t, for example */ //fzc: 在ngx_http_init_listening->ngx_http_add_addrs中添加

    ngx_log_t           log;
    ngx_log_t          *logp;

    size_t              pool_size;
    /* should be here because of the AcceptEx() preread */
    size_t              post_accept_buffer_size;
    /* should be here because of the deferred accept */
    ngx_msec_t          post_accept_timeout;

    ngx_listening_t    *previous;
    ngx_connection_t   *connection;

    unsigned            open:1;
    unsigned            remain:1;
    unsigned            ignore:1; //fzc: 为1时表示该listening结构体失效

    unsigned            bound:1;       /* already bound */
    unsigned            inherited:1;   /* inherited from previous process */
    unsigned            nonblocking_accept:1;
    unsigned            listen:1; //fzc: 在listen系统调用后,被置位
    unsigned            nonblocking:1;
    unsigned            shared:1;    /* shared between threads or processes */
    unsigned            addr_ntop:1; //fzc:? 为1时表示addr_text是否有值

#if (NGX_HAVE_INET6 && defined IPV6_V6ONLY)
    unsigned            ipv6only:1;
#endif
    unsigned            keepalive:2;

#if (NGX_HAVE_DEFERRED_ACCEPT)
    unsigned            deferred_accept:1;
    unsigned            delete_deferred:1;
    unsigned            add_deferred:1;
#ifdef SO_ACCEPTFILTER
    char               *accept_filter;
#endif
#endif
#if (NGX_HAVE_SETFIB)
    int                 setfib;
#endif

#if (NGX_HAVE_TCP_FASTOPEN)
    int                 fastopen;
#endif

};


typedef enum {
     NGX_ERROR_ALERT = 0,
     NGX_ERROR_ERR,
     NGX_ERROR_INFO,
     NGX_ERROR_IGNORE_ECONNRESET,
     NGX_ERROR_IGNORE_EINVAL
} ngx_connection_log_error_e;


typedef enum {
     NGX_TCP_NODELAY_UNSET = 0,
     NGX_TCP_NODELAY_SET,
     NGX_TCP_NODELAY_DISABLED
} ngx_connection_tcp_nodelay_e;


typedef enum {
     NGX_TCP_NOPUSH_UNSET = 0,
     NGX_TCP_NOPUSH_SET,
     NGX_TCP_NOPUSH_DISABLED
} ngx_connection_tcp_nopush_e;


#define NGX_LOWLEVEL_BUFFERED  0x0f
#define NGX_SSL_BUFFERED       0x01
#define NGX_SPDY_BUFFERED      0x02


struct ngx_connection_s { //fzc: ngx_connection_s是被动连接, 即客户端到nginx的连接
    void               *data; //fzc: 连接未使用时被充当构建空闲连接表free_connection的next指针, 连接建立时用来存储7层协议信息, 如ngx_http_connection_t(见ngx_http_init_connection)或者ngx_http_request_t(见ngx_http_wait_request_handler)
    ngx_event_t        *read; //fzc: 连接对应的读事件
    ngx_event_t        *write; //fzc: 连接对应的写事件

    ngx_socket_t        fd; //fzc: socket fd
    //fzc: 以下提供四个读写数据的方法指针说明每个连接可以自由的采用不同的接收和发送方法, 每个事件消费模块可以自行决定
    ngx_recv_pt         recv; //fzc: 接受网络字符流的方法
    ngx_send_pt         send; //fzc: 发送网络字符流的方法
    ngx_recv_chain_pt   recv_chain; //fzc: 以ngx_chain_t为参数来接受网络字符流的方法
    ngx_send_chain_pt   send_chain; //fzc: 以ngx_chain_t为参数来发送网络字符流的方法

    ngx_listening_t    *listening; //fzc: 该连接对应的listening信息, 表示是由该listening监听端口的读事件建立的连接

    off_t               sent; //fzc: 记录已发送的字节量

    ngx_log_t          *log;

    ngx_pool_t         *pool; //fzc: accept到的连接会新分配一个内存池, 且大小由listening的pool_size决定

    struct sockaddr    *sockaddr; //fzc: 以下三个为客户端的地址信息
    socklen_t           socklen;
    ngx_str_t           addr_text;

    ngx_str_t           proxy_protocol_addr;

#if (NGX_SSL)
    ngx_ssl_connection_t  *ssl;
#endif

    struct sockaddr    *local_sockaddr; //fzc: 本机的监听端口, 也就是listening监听对象中的sockaddr成员
    socklen_t           local_socklen;

    ngx_buf_t          *buffer; //fzc: 用于缓存客户端发来的响应数据, 每个事件消费模块自行决定从内存池分配多大空间给buffer字段, 例如http模块会按client_header_buffer_size配置项来分配大小, http框架会在ngx_http_wait_request_handler回调中分配buffer空间

    ngx_queue_t         queue; //fzc: 用来构建可复用连接队列, 队列头为cycle->reusable_connections_queue

    ngx_atomic_uint_t   number; //fzc: 表示全局范围内即该进程从启动监听到目前的第几次连接, 在ngx_event_accept内赋值

    ngx_uint_t          requests; //fzc: 处理的请求次数, 仅在ngx_http_create_request中被++递增

    unsigned            buffered:8; //fzc:? 标识缓存数据的业务类型, 任何事件消费模块都可以自定义需要的标志位, 这个buffered字段有8bit, 最多可同时表示8种不同的业务, 见ngx_http_request.h中NGX_HTTP_GZIP_BUFFERED等定义

    unsigned            log_error:3;     /* ngx_connection_log_error_e */ //fzc: 表示本连接记录日志时的日志等级

    unsigned            unexpected_eof:1; //fzc:? 表示不期待字符流结束, 目前是否有意义
    unsigned            timedout:1; //fzc: 表示连接是否已经超时
    unsigned            error:1; //fzc: 表示连接处理过程中是否发生错误
    unsigned            destroyed:1; //fzc: 表示连接是否已经销毁, 仅指套接字, 内存池是否销毁, ngx_connection_t结构体自身仍存在

    unsigned            idle:1; //fzc: 表示连接是否处于空闲状态, 如keepalive请求中的两次请求之间的状态
    unsigned            reusable:1; //fzc: 是否在复用状态, 即是否在cycle->reusable_connections_queue队列里
    unsigned            close:1; //fzc: 为1时表示连接需要关闭

    unsigned            sendfile:1; //fzc: 为1表示正在将文件中的数据发往连接的另一端
    unsigned            sndlowat:1; //fzc: 为1表示已经设置过发送缓冲区的lowat
    unsigned            tcp_nodelay:2;   /* ngx_connection_tcp_nodelay_e */ //fzc: 以下2个分别表示如果使用tcp的nodelay和nopush特性
    unsigned            tcp_nopush:2;    /* ngx_connection_tcp_nopush_e */

    unsigned            need_last_buf:1; //fzc: 为1时表示需要明确该连接上的请求处理完成后, 发送响应时是否需要等到响应chain完整, 即有chain中最后一个buf的last_buf标识为1, 才可以发送响应, 详见ngx_http_write_filter逻辑

#if (NGX_HAVE_IOCP)
    unsigned            accept_context_updated:1;
#endif

#if (NGX_HAVE_AIO_SENDFILE)
    unsigned            aio_sendfile:1; //fzc: 为1时表示使用异步io的方式将磁盘文件发送到另一端
    unsigned            busy_count:2;
    ngx_buf_t          *busy_sendfile;
#endif

#if (NGX_THREADS)
    ngx_atomic_t        lock;
#endif
};


ngx_listening_t *ngx_create_listening(ngx_conf_t *cf, void *sockaddr,
    socklen_t socklen);
ngx_int_t ngx_set_inherited_sockets(ngx_cycle_t *cycle);
ngx_int_t ngx_open_listening_sockets(ngx_cycle_t *cycle);
void ngx_configure_listening_sockets(ngx_cycle_t *cycle);
void ngx_close_listening_sockets(ngx_cycle_t *cycle);
void ngx_close_connection(ngx_connection_t *c);
ngx_int_t ngx_connection_local_sockaddr(ngx_connection_t *c, ngx_str_t *s,
    ngx_uint_t port);
ngx_int_t ngx_connection_error(ngx_connection_t *c, ngx_err_t err, char *text);

ngx_connection_t *ngx_get_connection(ngx_socket_t s, ngx_log_t *log);
void ngx_free_connection(ngx_connection_t *c);

void ngx_reusable_connection(ngx_connection_t *c, ngx_uint_t reusable);

#endif /* _NGX_CONNECTION_H_INCLUDED_ */
